Mock 开发：兼容 Proxy 代理与 Whitelist 白名单机制
概述
在前后端分离开发中，Mock 服务和 API 代理可能会产生冲突——两者都拦截 /api 前缀的请求。通过白名单（Whitelist）机制，可以精确控制哪些接口走 Mock、哪些走代理，实现两种模式的兼容。
问题分析
冲突场景
请求流程:
浏览器 → /api/users
↓
Vite Dev Server
↓
┌────────────────┐
│ Mock 插件 │ ← 拦截 /api/* 返回模拟数据
├────────────────┤
│ Proxy 代理 │ ← 转发 /api/* 到后端服务
└────────────────┘
问题：Mock 和 Proxy 都匹配 /api 前缀，请求只会被其中一个处理
text
两种模式
| 模式 | 数据来源 | 适用场景 |
|---|---|---|
| Mock | 本地模拟数据 | 后端接口未开发、独立前端开发 |
| Proxy | 后端真实服务 | 联调、测试环境 |
解决方案：Whitelist 白名单
环境变量配置
# .env.development
VITE_MOCK_ENABLE=true
# Whitelist：不走 Mock，走 Proxy 的接口列表
VITE_PROXY_WHITELIST=/api/auth,/api/upload,/api/payment
bash
Vite 配置
// vite.config.ts
import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'
import { viteMockServe } from 'vite-plugin-mock'
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), '')
const isMockEnabled = env.VITE_MOCK_ENABLE === 'true'
const whitelist = (env.VITE_PROXY_WHITELIST || '').split(',')
return {
plugins: [
vue(),
viteMockServe({
ignore: whitelist.length > 0 ? whitelist : undefined,
enable: isMockEnabled,
}),
],
server: {
proxy: {
'/api': {
target: 'http://localhost:3000',
changeOrigin: true,
// 仅白名单接口走代理
bypass: (req) => {
if (isMockEnabled && !whitelist.some(path => req.url?.startsWith(path))) {
return req.url // 让 Mock 插件处理
}
},
},
},
},
}
})
typescript
请求分流逻辑
// 判断请求是否应该走代理
function shouldUseProxy(url: string, whitelist: string[]): boolean {
return whitelist.some(path => url.startsWith(path))
}
// 请求处理流程：
// 1. 检查 Mock 是否启用
// 2. 检查请求 URL 是否在白名单中
// 3. 白名单 → 走 Proxy | 非白名单 → 走 Mock
typescript
调试技巧
# 测试 Mock 接口
curl http://localhost:5173/api/users # Mock 返回模拟数据
# 测试 Proxy 接口（白名单中的路径）
curl http://localhost:5173/api/auth/login # 转发到后端
# 切换模式：关闭 Mock
# 修改 .env.development
VITE_MOCK_ENABLE=false
# 重启 Vite 开发服务器
bash
配置检查清单
| 配置项 | Mock 模式 | Proxy 模式 | 混合模式 |
|---|---|---|---|
VITE_MOCK_ENABLE | true | false | true |
VITE_PROXY_WHITELIST | 空 | 全部接口 | 需走代理的接口 |
Mock 插件 enable | true | false | true + ignore |
Proxy bypass | 不需要 | 不需要 | 需要配置 |
实践要点
- Mock 插件的
enable必须设为true才能拦截请求，否则所有/api请求都会走 Proxy - 白名单配置在
.env文件中，不同环境可配置不同的白名单 - 修改
.env文件后需要重启 Vite 开发服务器 - 当发现 Mock 接口请求不到时，首先检查 Mock 插件的
enable状态 - 白名单方案虽然有效，但在接口数量多时维护成本较高，可考虑更灵活的匹配规则
↑